<?php
/**
 * Celebrio FileSystem module
 *
 * @copyright  Copyright (c) 2011 Celebrio Software
 * @package    Celebrio
 * @subpackage FileSystem
 */
namespace Celebrio\FileSystem\Drivers;

use Celebrio\FileSystem\DataFile;

/**
 * Interface for drivers which work with file (storage) system.
 * Every FileSystem driver should implement it, we expect such
 * implementatins: 
 * 
 * Local.php (already finished)
 * GDocs.php
 * Picasa.php
 * Ftp.php
 * AzureStorage.php
 * 
 * All those implementations should be placed in 
 * libs/Albireo/Modules/FileSystem to let the system know about
 * them. Implementation of this interface should implement
 * IModule as well.
 *
 * @author Honza, pavel
 */

interface IDriver {
    
    /**
     * Loads the file (or folder children) from storage and return it as Data File.
     *
     * @param DataFile $dataFile
     * @param bool $stream true when data should be streamed, false when
     *      it is required to store data to server memory
     * @return DataFile containing data or handler to data
     */
    public function load(DataFile $dataFile, $stream = false);

    /**
     * Saves the file (or folder) to storage
     *
     * @param DataFile $dataFile
     */
    public function save(DataFile $dataFile);

    /**
     * Moves the file (or folder with children) to another destination.
     * This function can also be used as rename function which includes
     * move and rename in the same time.
     *
     * @param DataFile $source file we want to move
     * @param DataFile $destination where we want to put new file
     */
    public function move(DataFile $source, DataFile $destination);

    /**
     * Deletes given file from storage.
     *
     * @param DataFile $dataFile
     */
    public function delete(DataFile $dataFile);

    /**
     * Basic query if given file exists on storage system
     *
     * @param DataFile $dataFile 
     */
    public function exists(DataFile $dataFile);
    
    /**
     * Function which is called when some change in owners occure
     * 
     * @param DataFile $dataFile
     */
    public function onChangeOwner(DataFile $datafile);


    //Note: function copy is realized in Virtual File System as load and save.
}
